<!DOCTYPE HTML>
<html>
<head>
<title>FileSelectFile | AutoHotkey</title>
<meta name="description" content="The FileSelectFile command displays a standard dialog that allows the user to open or save file(s)." />
<meta name="ahk:equiv-v2" content="lib/FileSelect.htm" />
<meta http-equiv="content-type" content="text/html; charset=utf-8">
<meta http-equiv="X-UA-Compatible" content="IE=edge">
<link href="../static/theme.css" rel="stylesheet" type="text/css" />
<script src="../static/content.js" type="text/javascript"></script>
</head>
<body>

<h1>FileSelectFile</h1>

<p>显示可以让用户打开或保存文件的标准对话框.</p>

<pre class="Syntax"><span class="func">FileSelectFile</span>, OutputVar <span class="optional">, Options, RootDir\Filename, Title, Filter</span></pre>
<h2 id="Parameters">参数</h2>
<dl>

  <dt>OutputVar</dt>
  <dd><p>用来保存用户选择的文件名的输出变量的名称. 如果用户取消了对话框(即不想选择文件), 则此变量被置空.</p></dd>

  <dt>Options</dt>
  <dd><p>如果省略, 则它默认为零, 相当于下面的任意选项都没有指定.</p>
      <p><strong>M</strong>: 多选. 指定字母 M 让用户可以使用 Shift+点击, Control+点击 或其他方法来选择多个文件. <strong>M</strong> 后面可以跟着下面描述的数字(例如, M 和 M1 都是有效的). 要逐个提取文件, 请参阅此页面底部的例子.</p>
      <p><strong>S</strong>: 保存对话框. 指定字母 S 让对话框显示保存按钮代替打开按钮. <strong>S</strong> 后面可以跟着下面描述的数字(或几个数的和)(例如, S 和 S16 都是有效的).</p>
      <p>即使同时省略 <strong>M</strong> 和 <strong>S</strong>, 仍然可以使用下面的数字. 要让多个数字同时生效, 请把它们加在一起. 例如, 如果要使用 1 和 2, 请指定数字 3.</p>
      <p><strong>1</strong>: 文件必须存在<br>
        <strong>2</strong>: 路径必须存在<br>
        <strong>8</strong>: 提示创建新文件<br>
        <strong>16</strong>: 提示覆盖文件<br>
        <strong>32</strong> <span class="ver">[v1.0.43.09+]:</span>
      按原样选择快捷方式(.lnk 文件) 而不把它们解析为它们的目标. 此选项也避免了通过文件夹快捷方式跳转到那个文件夹的情况.</p>
      <p>由于 "提示覆盖" 选项只有保存对话框支持, 因此在没有 "提示创建" 选项的情况下指定该选项也会使 "S" 选项生效. 同样, 当 "S" 选项存在时, "提示创建" 选项也没有效果. 指定数字 24 可以启用对话框支持的任何一种提示类型.</p></dd>

  <dt>RootDir\Filename</dt>
  <dd><p>如果存在, 则此参数包含下列的其中一个或两个:</p>
      <p><strong>RootDir</strong>: 根(起始) 目录, 如果未指定绝对路径, 则假定为 <a href="../Variables.htm#WorkingDir">%A_WorkingDir%</a> 中的子文件夹. 如果省略或为空, 则起始目录将为默认值, 这可能操作系统版本有关(它很可能是之前使用 FileSelectFile 时用户最近选择的目录). <span class="ver">[v1.0.43.10+]</span>: 在 Windows XP/2003 或早期系统中, 还可以指定 <a href="../misc/CLSID-List.htm">CLSID</a> 例如 <code>::{20d04fe0-3aea-1069-a2d8-08002b30309d}</code>(即我的电脑), 此时在 CLSID 后任何子目录都应该以反斜杠结尾(否则在最后一个反斜杠后的字符串会被解释为默认文件名, 这点在下面说明).</p>
      <p><strong>Filename</strong>: 初始显示对话框时在编辑区域的默认文件名. 只显示单独的文件名(不带路径). 要让对话框正确显示, 请确保不包含非法字符(例如 /&lt;|:").</p>
      <p>示例:</p>
      <pre class="no-highlight">C:\My Pictures\Default Image Name.gif  <em>; 同时使用了 <i>RootDir</i> 和 <i>Filename</i>.</em>
C:\My Pictures  <em>; 只使用了 <i>RootDir</i>.</em>
My Pictures  <em>; 只使用了 <i>RootDir</i>, 且它相对于当前工作目录.</em>
My File  <em>; 只使用了 <i>Filename</i>(但如果已存在 "My File" 的文件夹, 则它会被认为是 <i>RootDir</i>).</em></pre></dd>

  <dt>Title</dt>
  <dd><p>文件选择窗口的标题. 如果省略或为空, 则它默认为 "Select File - %A_ScriptName%"(即当前脚本的名称).</p></dd>

  <dt>Filter</dt>
  <dd><p>表示希望对话框显示的文件类型.</p>
      <p>例如: 文本文档 (*.txt)<br>
        例如: 音频文件 (*.wav; *.mp2; *.mp3)</p>
      <p>如果省略, 则过滤器默认为 所有文件(*.*). 在对话框 "文件类型" 菜单中, 文本文档 (*.txt) 选项还是可用的.</p>
    <p>否则, 过滤器使用指示的字符串, 不过在对话框的 "文件类型" 下拉列表中仍然提供了 所有文件(*.*) 选项. 要在过滤器中包含多个文件扩展名, 请使用分号分隔它们, 如上所示.</p></dd>

</dl>

<h2 id="Error_Handling">错误处理</h2>
<p><span class="ver">[v1.1.04+]</span>: 此命令失败时会抛出异常. 想了解更多信息, 请参阅<a href="Catch.htm#RuntimeErrors">运行时错误</a>.</p>
<p>如果用户没有选择文件却解除了对话框(例如按下了取消按钮), 则 <a href="../misc/ErrorLevel.htm">ErrorLevel</a> 被置为 1. 如果系统拒绝显示对话框(罕见), 那么它也被设置为 1. 否则被置为 0.</p>
<h2 id="Remarks">备注</h2>
<p>文件选择对话框通常是这样的:</p>
<img src="../static/pics/dlg_file.png" alt="FileSelectFile" />
<p>如果用户什么都没选(例如点击了取消), 则 <em>OutputVar</em> 被置空.</p>
<p>如果没有启用多选, 则 <em>OutputVar</em> 被设置为用户选择的单个文件的完整路径和名称.</p>
<p>如果使用了 M 选项(多选), 则 <em>OutputVar</em> 被设置为项目列表, 除了最后一个项目外的每个项目后都跟着换行符(`n). 列表中的首个项目是包含所有选择文件的路径(此路径仅在为根目录时才以反斜杠结尾, 例如 C:\). 其他项为选择的文件名(不带路径). 例如:</p>
<pre>C:\My Documents\New Folder [这是下面所有文件所在的路径]
test1.txt [这些是不含路径的文件名]
test2.txt
... 等等.</pre>
<p>(此页面底部的例子演示了如何逐个提取这些文件.)</p>
<p>如果启用了多选, 则所有选择文件名的总长度被限制为 64 KB. 不过这通常足够容纳几千个文件, 如果超出此限制则 <em>OutputVar</em> 会被置空.</p>
<p>GUI 窗口可以使用 <a href="Gui.htm#OwnDialogs">Gui +OwnDialogs</a> 的方法显示文件选择模式对话框. 模式对话框在其消失之前会阻止用户与 GUI 窗口进行交互.</p>
<p>已知限制: 在显示 FileSelectFile 对话框时运行的<a href="SetTimer.htm">计时器</a>会延迟用户在对话框中点击的效果到计时器结束之后. 要变通解决此问题, 请避免使用子程序需要很长时间来完成的计时器, 或在显示对话框期间禁用所有计时器:</p>
<pre><a href="Thread.htm">Thread</a>, NoTimers
FileSelectFile, OutputVar
Thread, NoTimers, false</pre>
<p><span class="ver">[v1.0.25.06+]</span>: 多选选项 "4" 已过时. 然而, 考虑到和旧脚本的兼容, 这个选项仍然可用. 具体是, 如果用户只选择了一个文件, 则 <em>OutputVar</em> 会包含这个文件的完整路径和名称跟着换行符(`n). 如果用户选择了多个文件, 则格式和上面描述的 M 选项相同, 不过最后一项也会以换行符(`n) 结束.</p>
<h2 id="Related">相关</h2>
<p><a href="FileSelectFolder.htm">FileSelectFolder</a>, <a href="MsgBox.htm">MsgBox</a>, <a href="InputBox.htm">InputBox</a>, <a href="ToolTip.htm">ToolTip</a>, <a href="Gui.htm">GUI</a>, <a href="../misc/CLSID-List.htm">CLSID 列表</a>, <a href="LoopParse.htm">解析循环</a>, <a href="SplitPath.htm">SplitPath</a></p>
<p>此外, 操作系统提供了标准的对话框让用户选取字体, 颜色或图标. 使用 <a href="DllCall.htm">DllCall()</a> 可以显示这些对话框, 演示的例子请参阅 <a href="https://github.com/majkinetor/mm-autohotkey/tree/master/Dlg">GitHub</a>.</p>
<h2 id="Examples">示例</h2>
<div class="ex" id="ExBasic">
<p><a class="ex_number" href="#ExBasic"></a> 允许用户选择当前存在的 .txt 或 .doc 文件.</p>
<pre>FileSelectFile, SelectedFile, 3, , Open a file, Text Documents (*.txt; *.doc)
if (SelectedFile = "")
    MsgBox, The user didn't select anything.
else
    MsgBox, The user selected the following:`n%SelectedFile%</pre>
</div>

<div class="ex" id="ExCLSID">
<p><aclass="ex_number" href="#ExCLSID"></a> <a href="../misc/CLSID-List.htm">CLSID</a> 的例子(需要 XP/2003 或早期系统). 允许用户在回收站中选择一个文件. 注意, 这个例子只适用于 Windows XP/2003 或更早的操作系统.</p>
<pre>FileSelectFile, OutputVar,, ::{645ff040-5081-101b-9f08-00aa002f954e}  <em>; 回收站.</em></pre>
</div>

<div class="ex" id="ExMulti">
<p><a class="ex_number" href="#ExMulti"></a> 允许用户选择多个当前存在的文件.</p>
<pre>FileSelectFile, files, M3  <em>; M3 = 选择多个现有文件.</em>
if (files = "")
{
    MsgBox, The user pressed cancel.
    return
}
Loop, parse, files, `n
{
    if (A_Index = 1)
        MsgBox, The selected files are all contained in %A_LoopField%.
    else
    {
        MsgBox, 4, , The next file is %A_LoopField%.  Continue?
        IfMsgBox, No, break
    }
}
return</pre>
</div>

</body>
</html>